/*
 * Copyright [2021-present] [ahoo wang <ahoowang@qq.com> (https://github.com/Ahoo-Wang)].
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *      http://www.apache.org/licenses/LICENSE-2.0
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package me.ahoo.cosid;

import me.ahoo.cosid.stat.Stat;
import me.ahoo.cosid.stat.Statistical;

import com.google.errorprone.annotations.ThreadSafe;
import jakarta.annotation.Nonnull;

/**
 * ID converter for transforming between numeric and string representations of IDs.
 * 
 * <p>This interface defines the contract for converting distributed IDs between
 * their numeric ({@code long}) and string representations. This is useful when
 * you need to store IDs as strings in databases or URLs but work with them as
 * numbers in application logic.
 * 
 * <p>Common implementations include:
 * <ul>
 *   <li>{@link me.ahoo.cosid.converter.Radix62IdConverter} - Converts to radix-62 strings</li>
 *   <li>{@link me.ahoo.cosid.converter.Radix36IdConverter} - Converts to radix-36 strings</li>
 *   <li>{@link me.ahoo.cosid.converter.ToStringIdConverter} - Simple string conversion</li>
 * </ul>
 * 
 * <p>Implementations of this interface are expected to be thread-safe and can be
 * used concurrently across multiple threads.
 *
 * @author ahoo wang
 */
@ThreadSafe
public interface IdConverter extends Statistical {
    
    /**
     * Convert a {@code long} type ID to its {@link String} representation.
     * 
     * <p>This method transforms a numeric ID into a string format according to the
     * specific conversion algorithm implemented by the converter. For example,
     * a radix converter might convert the number 12345 to "3d7".
     *
     * @param id The {@code long} type ID to convert
     * @return The {@link String} representation of the ID
     */
    @Nonnull
    String asString(long id);
    
    /**
     * Convert a {@link String} type ID back to its {@code long} representation.
     * 
     * <p>This method performs the reverse operation of {@link #asString(long)},
     * transforming a string ID back into its original numeric form. Implementations
     * should be able to correctly parse strings generated by their {@link #asString(long)}
     * method.
     *
     * @param idString The {@link String} type ID to convert
     * @return The {@code long} representation of the ID
     */
    long asLong(@Nonnull String idString);
    
    /**
     * Get statistical information about this converter.
     * 
     * <p>This method provides basic statistical information about the converter,
     * including its implementation class name.
     *
     * @return Statistical information about this converter
     */
    @Override
    default Stat stat() {
        return Stat.simple(getClass().getSimpleName());
    }
}
